<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en-US">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=11"/>
<meta name="generator" content="Doxygen 1.13.2"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>CAD_Doc: Mocking Reference</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<script type="text/javascript" src="clipboard.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="cookie.js"></script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
  $(function() { init_search(); });
/* @license-end */
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr id="projectrow">
  <td id="projectalign">
   <div id="projectname">CAD_Doc<span id="projectnumber">&#160;1.0</span>
   </div>
   <div id="projectbrief">cad synopsis</div>
  </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
        <span class="left">
          <span id="MSearchSelect"                onmouseover="return searchBox.OnSearchSelectShow()"                onmouseout="return searchBox.OnSearchSelectHide()">&#160;</span>
          <input type="text" id="MSearchField" value="" placeholder="Search" accesskey="S"
               onfocus="searchBox.OnSearchFieldFocus(true)" 
               onblur="searchBox.OnSearchFieldFocus(false)" 
               onkeyup="searchBox.OnSearchFieldChange(event)"/>
          </span><span class="right">
            <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
          </span>
        </div>
</td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.13.2 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
var searchBox = new SearchBox("searchBox", "search/",'.html');
/* @license-end */
</script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function() { codefold.init(0); });
/* @license-end */
</script>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:d3d9a9a6595521f9666a5e94cc830dab83b65699&amp;dn=expat.txt MIT */
$(function(){initNavTree('md__build_2__deps_2googletest-src_2docs_2reference_2mocking.html',''); initResizable(true); });
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
     onmouseover="return searchBox.OnSearchSelectShow()"
     onmouseout="return searchBox.OnSearchSelectHide()"
     onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>

<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<div id="MSearchResults">
<div class="SRPage">
<div id="SRIndex">
<div id="SRResults"></div>
<div class="SRStatus" id="Loading">Loading...</div>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
</div>
</div>
</div>
</div>

<div><div class="header">
  <div class="headertitle"><div class="title">Mocking Reference</div></div>
</div><!--header-->
<div class="contents">
<div class="textblock"><p><a class="anchor" id="autotoc_md262"></a></p>
<p>This page lists the facilities provided by GoogleTest for creating and working with mock objects. To use them, include the header <code><a class="el" href="gmock_8h_source.html">gmock/gmock.h</a></code>.</p>
<h1><a class="anchor" id="macros"></a>
Macros</h1>
<p>GoogleTest defines the following macros for working with mocks.</p>
<h2><a class="anchor" id="MOCK_METHOD"></a>
MOCK_METHOD</h2>
<p><code>MOCK_METHOD(</code>*<code>return_type</code>*<code>,</code>*<code>method_name</code>*<code>, (</code>*<code>args...</code>*<code>));</code> \ <code>MOCK_METHOD(</code>*<code>return_type</code>*<code>,</code>*<code>method_name</code>*<code>, (</code>*<code>args...</code>*<code>), (</code>*<code>specs...</code>*<code>));</code></p>
<p>Defines a mock method <em><code>method_name</code></em> with arguments <code>(</code>*<code>args...</code>*<code>)</code> and return type <em><code>return_type</code></em> within a mock class.</p>
<p>The parameters of <code>MOCK_METHOD</code> mirror the method declaration. The optional fourth parameter <em><code>specs...</code></em> is a comma-separated list of qualifiers. The following qualifiers are accepted:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">Qualifier   </th><th class="markdownTableHeadNone">Meaning    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>const</code>   </td><td class="markdownTableBodyNone">Makes the mocked method a <code>const</code> method. Required if overriding a <code>const</code> method.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><code>override</code>   </td><td class="markdownTableBodyNone">Marks the method with <code>override</code>. Recommended if overriding a <code>virtual</code> method.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>noexcept</code>   </td><td class="markdownTableBodyNone">Marks the method with <code>noexcept</code>. Required if overriding a <code>noexcept</code> method.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><code>Calltype(</code>*<code>calltype</code>*<code>)</code>   </td><td class="markdownTableBodyNone">Sets the call type for the method, for example <code>Calltype(STDMETHODCALLTYPE)</code>. Useful on Windows.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>ref(</code>*<code>qualifier</code>*<code>)</code>   </td><td class="markdownTableBodyNone">Marks the method with the given reference qualifier, for example <code>ref(&amp;)</code> or <code>ref(&amp;&amp;)</code>. Required if overriding a method that has a reference qualifier.   </td></tr>
</table>
<p>Note that commas in arguments prevent <code>MOCK_METHOD</code> from parsing the arguments correctly if they are not appropriately surrounded by parentheses. See the following example:</p>
<div class="fragment"><div class="line"><span class="keyword">class </span>MyMock {</div>
<div class="line"> <span class="keyword">public</span>:</div>
<div class="line">  <span class="comment">// The following 2 lines will not compile due to commas in the arguments:</span></div>
<div class="line">  MOCK_METHOD(std::pair&lt;bool, int&gt;, GetPair, ());              <span class="comment">// Error!</span></div>
<div class="line">  MOCK_METHOD(<span class="keywordtype">bool</span>, CheckMap, (std::map&lt;int, double&gt;, <span class="keywordtype">bool</span>));  <span class="comment">// Error!</span></div>
<div class="line"> </div>
<div class="line">  <span class="comment">// One solution - wrap arguments that contain commas in parentheses:</span></div>
<div class="line">  MOCK_METHOD((std::pair&lt;bool, int&gt;), GetPair, ());</div>
<div class="line">  MOCK_METHOD(<span class="keywordtype">bool</span>, CheckMap, ((std::map&lt;int, double&gt;), <span class="keywordtype">bool</span>));</div>
<div class="line"> </div>
<div class="line">  <span class="comment">// Another solution - use type aliases:</span></div>
<div class="line">  <span class="keyword">using </span>BoolAndInt = std::pair&lt;bool, int&gt;;</div>
<div class="line">  MOCK_METHOD(BoolAndInt, GetPair, ());</div>
<div class="line">  <span class="keyword">using </span>MapIntDouble = std::map&lt;int, double&gt;;</div>
<div class="line">  MOCK_METHOD(<span class="keywordtype">bool</span>, CheckMap, (MapIntDouble, <span class="keywordtype">bool</span>));</div>
<div class="line">};</div>
</div><!-- fragment --><p><code>MOCK_METHOD</code> must be used in the <code>public:</code> section of a mock class definition, regardless of whether the method being mocked is <code>public</code>, <code>protected</code>, or <code>private</code> in the base class.</p>
<h2><a class="anchor" id="EXPECT_CALL"></a>
EXPECT_CALL</h2>
<p><code>EXPECT_CALL(</code>*<code>mock_object</code>*<code>,</code>*<code>method_name</code>*<code>(</code>*<code>matchers...</code>*<code>))</code></p>
<p>Creates an <a href="../gmock_for_dummies.md#setting-expectations">expectation</a> that the method <em><code>method_name</code></em> of the object <em><code>mock_object</code></em> is called with arguments that match the given matchers <em><code>matchers...</code></em>. <code>EXPECT_CALL</code> must precede any code that exercises the mock object.</p>
<p>The parameter <em><code>matchers...</code></em> is a comma-separated list of <a href="../gmock_for_dummies.md#matchers-what-arguments-do-we-expect">matchers</a> that correspond to each argument of the method <em><code>method_name</code></em>. The expectation will apply only to calls of <em><code>method_name</code></em> whose arguments match all of the matchers. If <code>(</code>*<code>matchers...</code>*<code>)</code> is omitted, the expectation behaves as if each argument's matcher were a <a href="matchers.md#wildcard">wildcard matcher (<code>_</code>)</a>. See the <a class="el" href="md__build_2__deps_2googletest-src_2docs_2reference_2matchers.html">Matchers Reference</a> for a list of all built-in matchers.</p>
<p>The following chainable clauses can be used to modify the expectation, and they must be used in the following order:</p>
<div class="fragment"><div class="line">EXPECT_CALL(mock_object, method_name(matchers...))</div>
<div class="line">    .With(multi_argument_matcher)  <span class="comment">// Can be used at most once</span></div>
<div class="line">    .Times(cardinality)            <span class="comment">// Can be used at most once</span></div>
<div class="line">    .InSequence(sequences...)      <span class="comment">// Can be used any number of times</span></div>
<div class="line">    .After(expectations...)        <span class="comment">// Can be used any number of times</span></div>
<div class="line">    .WillOnce(action)              <span class="comment">// Can be used any number of times</span></div>
<div class="line">    .WillRepeatedly(action)        <span class="comment">// Can be used at most once</span></div>
<div class="line">    .RetiresOnSaturation();        <span class="comment">// Can be used at most once</span></div>
</div><!-- fragment --><p>See details for each modifier clause below.</p>
<h3><a class="anchor" id="autotoc_md263"></a>
With {#EXPECT_CALL.With}</h3>
<p><code>.With(</code>*<code>multi_argument_matcher</code>*<code>)</code></p>
<p>Restricts the expectation to apply only to mock function calls whose arguments as a whole match the multi-argument matcher <em><code>multi_argument_matcher</code></em>.</p>
<p>GoogleTest passes all of the arguments as one tuple into the matcher. The parameter <em><code>multi_argument_matcher</code></em> must thus be a matcher of type <code><a class="el" href="class_matcher.html">Matcher</a>&lt;std::tuple&lt;A1, ..., An&gt;&gt;</code>, where <code>A1, ..., An</code> are the types of the function arguments.</p>
<p>For example, the following code sets the expectation that <code>my_mock.SetPosition()</code> is called with any two arguments, the first argument being less than the second:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::_;</div>
<div class="line"><span class="keyword">using </span>::testing::Lt;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(my_mock, SetPosition(_, _))</div>
<div class="line">    .With(Lt());</div>
</div><!-- fragment --><p>GoogleTest provides some built-in matchers for 2-tuples, including the <code>Lt()</code> matcher above. See <a href="matchers.md#MultiArgMatchers">Multi-argument Matchers</a>.</p>
<p>The <code>With</code> clause can be used at most once on an expectation and must be the first clause.</p>
<h3><a class="anchor" id="autotoc_md264"></a>
Times {#EXPECT_CALL.Times}</h3>
<p><code>.Times(</code>*<code>cardinality</code>*<code>)</code></p>
<p>Specifies how many times the mock function call is expected.</p>
<p>The parameter <em><code>cardinality</code></em> represents the number of expected calls and can be one of the following, all defined in the <code>testing</code> namespace:</p>
<table class="markdownTable">
<tr class="markdownTableHead">
<th class="markdownTableHeadNone">Cardinality   </th><th class="markdownTableHeadNone">Meaning    </th></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>AnyNumber()</code>   </td><td class="markdownTableBodyNone">The function can be called any number of times.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><code>AtLeast(n)</code>   </td><td class="markdownTableBodyNone">The function call is expected at least <em>n</em> times.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>AtMost(n)</code>   </td><td class="markdownTableBodyNone">The function call is expected at most <em>n</em> times.    </td></tr>
<tr class="markdownTableRowEven">
<td class="markdownTableBodyNone"><code>Between(m, n)</code>   </td><td class="markdownTableBodyNone">The function call is expected between <em>m</em> and <em>n</em> times, inclusive.    </td></tr>
<tr class="markdownTableRowOdd">
<td class="markdownTableBodyNone"><code>Exactly(n)</code> or <code>n</code>   </td><td class="markdownTableBodyNone">The function call is expected exactly <em>n</em> times. If <em>n</em> is 0, the call should never happen.   </td></tr>
</table>
<p>If the <code>Times</code> clause is omitted, GoogleTest infers the cardinality as follows:</p>
<ul>
<li>If neither `WillOnce` nor `WillRepeatedly` are specified, the inferred cardinality is <code>Times(1)</code>.</li>
<li>If there are <em>n</em> <code>WillOnce</code> clauses and no <code>WillRepeatedly</code> clause, where <em>n</em> &gt;= 1, the inferred cardinality is <code>Times(n)</code>.</li>
<li>If there are <em>n</em> <code>WillOnce</code> clauses and one <code>WillRepeatedly</code> clause, where <em>n</em> &gt;= 0, the inferred cardinality is <code>Times(AtLeast(n))</code>.</li>
</ul>
<p>The <code>Times</code> clause can be used at most once on an expectation.</p>
<h3><a class="anchor" id="autotoc_md265"></a>
InSequence {#EXPECT_CALL.InSequence}</h3>
<p><code>.InSequence(</code>*<code>sequences...</code>*<code>)</code></p>
<p>Specifies that the mock function call is expected in a certain sequence.</p>
<p>The parameter <em><code>sequences...</code></em> is any number of <a class="el" href="#Sequence">`Sequence`</a> objects. Expected calls assigned to the same sequence are expected to occur in the order the expectations are declared.</p>
<p>For example, the following code sets the expectation that the <code>Reset()</code> method of <code>my_mock</code> is called before both <code>GetSize()</code> and <code>Describe()</code>, and <code>GetSize()</code> and <code>Describe()</code> can occur in any order relative to each other:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Sequence;</div>
<div class="line">Sequence s1, s2;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(my_mock, Reset())</div>
<div class="line">    .InSequence(s1, s2);</div>
<div class="line">EXPECT_CALL(my_mock, GetSize())</div>
<div class="line">    .InSequence(s1);</div>
<div class="line">EXPECT_CALL(my_mock, Describe())</div>
<div class="line">    .InSequence(s2);</div>
</div><!-- fragment --><p>The <code>InSequence</code> clause can be used any number of times on an expectation.</p>
<p>See also the <a class="el" href="#InSequence">`InSequence` class</a>.</p>
<h3><a class="anchor" id="autotoc_md266"></a>
After {#EXPECT_CALL.After}</h3>
<p><code>.After(</code>*<code>expectations...</code>*<code>)</code></p>
<p>Specifies that the mock function call is expected to occur after one or more other calls.</p>
<p>The parameter <em><code>expectations...</code></em> can be up to five <a class="el" href="#Expectation">`Expectation`</a> or <a class="el" href="#ExpectationSet">`ExpectationSet`</a> objects. The mock function call is expected to occur after all of the given expectations.</p>
<p>For example, the following code sets the expectation that the <code>Describe()</code> method of <code>my_mock</code> is called only after both <code>InitX()</code> and <code>InitY()</code> have been called.</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Expectation;</div>
<div class="line">...</div>
<div class="line">Expectation init_x = EXPECT_CALL(my_mock, InitX());</div>
<div class="line">Expectation init_y = EXPECT_CALL(my_mock, InitY());</div>
<div class="line">EXPECT_CALL(my_mock, Describe())</div>
<div class="line">    .After(init_x, init_y);</div>
</div><!-- fragment --><p>The <code>ExpectationSet</code> object is helpful when the number of prerequisites for an expectation is large or variable, for example:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::ExpectationSet;</div>
<div class="line">...</div>
<div class="line">ExpectationSet all_inits;</div>
<div class="line"><span class="comment">// Collect all expectations of InitElement() calls</span></div>
<div class="line"><span class="keywordflow">for</span> (<span class="keywordtype">int</span> i = 0; i &lt; element_count; i++) {</div>
<div class="line">  all_inits += EXPECT_CALL(my_mock, InitElement(i));</div>
<div class="line">}</div>
<div class="line">EXPECT_CALL(my_mock, Describe())</div>
<div class="line">    .After(all_inits);  <span class="comment">// Expect Describe() call after all InitElement() calls</span></div>
</div><!-- fragment --><p>The <code>After</code> clause can be used any number of times on an expectation.</p>
<h3><a class="anchor" id="autotoc_md267"></a>
WillOnce {#EXPECT_CALL.WillOnce}</h3>
<p><code>.WillOnce(</code>*<code>action</code>*<code>)</code></p>
<p>Specifies the mock function's actual behavior when invoked, for a single matching function call.</p>
<p>The parameter <em><code>action</code></em> represents the <a href="../gmock_for_dummies.md#actions-what-should-it-do">action</a> that the function call will perform. See the <a class="el" href="md__build_2__deps_2googletest-src_2docs_2reference_2actions.html">Actions Reference</a> for a list of built-in actions.</p>
<p>The use of <code>WillOnce</code> implicitly sets a cardinality on the expectation when <code>Times</code> is not specified. See `Times`.</p>
<p>Each matching function call will perform the next action in the order declared. For example, the following code specifies that <code>my_mock.GetNumber()</code> is expected to be called exactly 3 times and will return <code>1</code>, <code>2</code>, and <code>3</code> respectively on the first, second, and third calls:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Return;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(my_mock, GetNumber())</div>
<div class="line">    .WillOnce(Return(1))</div>
<div class="line">    .WillOnce(Return(2))</div>
<div class="line">    .WillOnce(Return(3));</div>
</div><!-- fragment --><p>The <code>WillOnce</code> clause can be used any number of times on an expectation. Unlike <code>WillRepeatedly</code>, the action fed to each <code>WillOnce</code> call will be called at most once, so may be a move-only type and/or have an <code>&amp;&amp;</code>-qualified call operator.</p>
<h3><a class="anchor" id="autotoc_md268"></a>
WillRepeatedly {#EXPECT_CALL.WillRepeatedly}</h3>
<p><code>.WillRepeatedly(</code>*<code>action</code>*<code>)</code></p>
<p>Specifies the mock function's actual behavior when invoked, for all subsequent matching function calls. Takes effect after the actions specified in the `WillOnce` clauses, if any, have been performed.</p>
<p>The parameter <em><code>action</code></em> represents the <a href="../gmock_for_dummies.md#actions-what-should-it-do">action</a> that the function call will perform. See the <a class="el" href="md__build_2__deps_2googletest-src_2docs_2reference_2actions.html">Actions Reference</a> for a list of built-in actions.</p>
<p>The use of <code>WillRepeatedly</code> implicitly sets a cardinality on the expectation when <code>Times</code> is not specified. See `Times`.</p>
<p>If any <code>WillOnce</code> clauses have been specified, matching function calls will perform those actions before the action specified by <code>WillRepeatedly</code>. See the following example:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Return;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(my_mock, GetName())</div>
<div class="line">    .WillRepeatedly(Return(<span class="stringliteral">&quot;John Doe&quot;</span>));  <span class="comment">// Return &quot;John Doe&quot; on all calls</span></div>
<div class="line"> </div>
<div class="line">EXPECT_CALL(my_mock, GetNumber())</div>
<div class="line">    .WillOnce(Return(42))        <span class="comment">// Return 42 on the first call</span></div>
<div class="line">    .WillRepeatedly(Return(7));  <span class="comment">// Return 7 on all subsequent calls</span></div>
</div><!-- fragment --><p>The <code>WillRepeatedly</code> clause can be used at most once on an expectation.</p>
<h3><a class="anchor" id="autotoc_md269"></a>
RetiresOnSaturation {#EXPECT_CALL.RetiresOnSaturation}</h3>
<p><code>.RetiresOnSaturation()</code></p>
<p>Indicates that the expectation will no longer be active after the expected number of matching function calls has been reached.</p>
<p>The <code>RetiresOnSaturation</code> clause is only meaningful for expectations with an upper-bounded cardinality. The expectation will <em>retire</em> (no longer match any function calls) after it has been <em>saturated</em> (the upper bound has been reached). See the following example:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::_;</div>
<div class="line"><span class="keyword">using </span>::testing::AnyNumber;</div>
<div class="line">...</div>
<div class="line">EXPECT_CALL(my_mock, SetNumber(_))  <span class="comment">// Expectation 1</span></div>
<div class="line">    .Times(AnyNumber());</div>
<div class="line">EXPECT_CALL(my_mock, SetNumber(7))  <span class="comment">// Expectation 2</span></div>
<div class="line">    .Times(2)</div>
<div class="line">    .RetiresOnSaturation();</div>
</div><!-- fragment --><p>In the above example, the first two calls to <code>my_mock.SetNumber(7)</code> match expectation 2, which then becomes inactive and no longer matches any calls. A third call to <code>my_mock.SetNumber(7)</code> would then match expectation 1. Without <code>RetiresOnSaturation()</code> on expectation 2, a third call to <code>my_mock.SetNumber(7)</code> would match expectation 2 again, producing a failure since the limit of 2 calls was exceeded.</p>
<p>The <code>RetiresOnSaturation</code> clause can be used at most once on an expectation and must be the last clause.</p>
<h2><a class="anchor" id="ON_CALL"></a>
ON_CALL</h2>
<p><code>ON_CALL(</code>*<code>mock_object</code>*<code>,</code>*<code>method_name</code>*<code>(</code>*<code>matchers...</code>*<code>))</code></p>
<p>Defines what happens when the method <em><code>method_name</code></em> of the object <em><code>mock_object</code></em> is called with arguments that match the given matchers <em><code>matchers...</code></em>. Requires a modifier clause to specify the method's behavior. <em>Does not</em> set any expectations that the method will be called.</p>
<p>The parameter <em><code>matchers...</code></em> is a comma-separated list of <a href="../gmock_for_dummies.md#matchers-what-arguments-do-we-expect">matchers</a> that correspond to each argument of the method <em><code>method_name</code></em>. The <code>ON_CALL</code> specification will apply only to calls of <em><code>method_name</code></em> whose arguments match all of the matchers. If <code>(</code>*<code>matchers...</code>*<code>)</code> is omitted, the behavior is as if each argument's matcher were a <a href="matchers.md#wildcard">wildcard matcher (<code>_</code>)</a>. See the <a class="el" href="md__build_2__deps_2googletest-src_2docs_2reference_2matchers.html">Matchers Reference</a> for a list of all built-in matchers.</p>
<p>The following chainable clauses can be used to set the method's behavior, and they must be used in the following order:</p>
<div class="fragment"><div class="line">ON_CALL(mock_object, method_name(matchers...))</div>
<div class="line">    .With(multi_argument_matcher)  <span class="comment">// Can be used at most once</span></div>
<div class="line">    .WillByDefault(action);        <span class="comment">// Required</span></div>
</div><!-- fragment --><p>See details for each modifier clause below.</p>
<h3><a class="anchor" id="autotoc_md270"></a>
With {#ON_CALL.With}</h3>
<p><code>.With(</code>*<code>multi_argument_matcher</code>*<code>)</code></p>
<p>Restricts the specification to only mock function calls whose arguments as a whole match the multi-argument matcher <em><code>multi_argument_matcher</code></em>.</p>
<p>GoogleTest passes all of the arguments as one tuple into the matcher. The parameter <em><code>multi_argument_matcher</code></em> must thus be a matcher of type <code><a class="el" href="class_matcher.html">Matcher</a>&lt;std::tuple&lt;A1, ..., An&gt;&gt;</code>, where <code>A1, ..., An</code> are the types of the function arguments.</p>
<p>For example, the following code sets the default behavior when <code>my_mock.SetPosition()</code> is called with any two arguments, the first argument being less than the second:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::_;</div>
<div class="line"><span class="keyword">using </span>::testing::Lt;</div>
<div class="line"><span class="keyword">using </span>::testing::Return;</div>
<div class="line">...</div>
<div class="line">ON_CALL(my_mock, SetPosition(_, _))</div>
<div class="line">    .With(Lt())</div>
<div class="line">    .WillByDefault(Return(<span class="keyword">true</span>));</div>
</div><!-- fragment --><p>GoogleTest provides some built-in matchers for 2-tuples, including the <code>Lt()</code> matcher above. See <a href="matchers.md#MultiArgMatchers">Multi-argument Matchers</a>.</p>
<p>The <code>With</code> clause can be used at most once with each <code>ON_CALL</code> statement.</p>
<h3><a class="anchor" id="autotoc_md271"></a>
WillByDefault {#ON_CALL.WillByDefault}</h3>
<p><code>.WillByDefault(</code>*<code>action</code>*<code>)</code></p>
<p>Specifies the default behavior of a matching mock function call.</p>
<p>The parameter <em><code>action</code></em> represents the <a href="../gmock_for_dummies.md#actions-what-should-it-do">action</a> that the function call will perform. See the <a class="el" href="md__build_2__deps_2googletest-src_2docs_2reference_2actions.html">Actions Reference</a> for a list of built-in actions.</p>
<p>For example, the following code specifies that by default, a call to <code>my_mock.Greet()</code> will return <code>"hello"</code>:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Return;</div>
<div class="line">...</div>
<div class="line">ON_CALL(my_mock, Greet())</div>
<div class="line">    .WillByDefault(Return(<span class="stringliteral">&quot;hello&quot;</span>));</div>
</div><!-- fragment --><p>The action specified by <code>WillByDefault</code> is superseded by the actions specified on a matching <code>EXPECT_CALL</code> statement, if any. See the `WillOnce` and `WillRepeatedly` clauses of <code>EXPECT_CALL</code>.</p>
<p>The <code>WillByDefault</code> clause must be used exactly once with each <code>ON_CALL</code> statement.</p>
<h1><a class="anchor" id="classes"></a>
Classes</h1>
<p>GoogleTest defines the following classes for working with mocks.</p>
<h2><a class="anchor" id="DefaultValue"></a>
Setting the Default Value for a Return Type</h2>
<p><code><a class="el" href="classtesting_1_1_default_value.html">testing::DefaultValue</a>&lt;T&gt;</code></p>
<p>Allows a user to specify the default value for a type <code>T</code> that is both copyable and publicly destructible (i.e. anything that can be used as a function return type). For mock functions with a return type of <code>T</code>, this default value is returned from function calls that do not specify an action.</p>
<p>Provides the static methods <code>Set()</code>, <code>SetFactory()</code>, and <code>Clear()</code> to manage the default value:</p>
<div class="fragment"><div class="line"><span class="comment">// Sets the default value to be returned. T must be copy constructible.</span></div>
<div class="line">DefaultValue&lt;T&gt;::Set(value);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Sets a factory. Will be invoked on demand. T must be move constructible.</span></div>
<div class="line">T MakeT();</div>
<div class="line">DefaultValue&lt;T&gt;::SetFactory(&amp;MakeT);</div>
<div class="line"> </div>
<div class="line"><span class="comment">// Unsets the default value.</span></div>
<div class="line">DefaultValue&lt;T&gt;::Clear();</div>
</div><!-- fragment --><h2><a class="anchor" id="NiceMock"></a>
NiceMock</h2>
<p><code><a class="el" href="classtesting_1_1_nice_mock.html">testing::NiceMock</a>&lt;T&gt;</code></p>
<p>Represents a mock object that suppresses warnings on <a href="../gmock_cook_book.md#uninteresting-vs-unexpected">uninteresting calls</a>. The template parameter <code>T</code> is any mock class, except for another <code>NiceMock</code>, <code><a class="el" href="class_naggy_mock.html">NaggyMock</a></code>, or <code>StrictMock</code>.</p>
<p>Usage of <code>NiceMock&lt;T&gt;</code> is analogous to usage of <code>T</code>. <code>NiceMock&lt;T&gt;</code> is a subclass of <code>T</code>, so it can be used wherever an object of type <code>T</code> is accepted. In addition, <code>NiceMock&lt;T&gt;</code> can be constructed with any arguments that a constructor of <code>T</code> accepts.</p>
<p>For example, the following code suppresses warnings on the mock <code>my_mock</code> of type <code>MockClass</code> if a method other than <code>DoSomething()</code> is called:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::<a class="code hl_class" href="classtesting_1_1_nice_mock.html">testing::NiceMock</a>;</div>
<div class="line">...</div>
<div class="line">NiceMock&lt;MockClass&gt; my_mock(<span class="stringliteral">&quot;some&quot;</span>, <span class="stringliteral">&quot;args&quot;</span>);</div>
<div class="line">EXPECT_CALL(my_mock, DoSomething());</div>
<div class="line">... code that uses my_mock ...</div>
<div class="ttc" id="aclasstesting_1_1_nice_mock_html"><div class="ttname"><a href="classtesting_1_1_nice_mock.html">testing::NiceMock</a></div><div class="ttdef"><b>Definition</b> gmock-nice-strict.h:151</div></div>
</div><!-- fragment --><p><code>NiceMock&lt;T&gt;</code> only works for mock methods defined using the <code>MOCK_METHOD</code> macro directly in the definition of class <code>T</code>. If a mock method is defined in a base class of <code>T</code>, a warning might still be generated.</p>
<p><code>NiceMock&lt;T&gt;</code> might not work correctly if the destructor of <code>T</code> is not virtual.</p>
<h2><a class="anchor" id="NaggyMock"></a>
NaggyMock</h2>
<p><code><a class="el" href="classtesting_1_1_naggy_mock.html">testing::NaggyMock</a>&lt;T&gt;</code></p>
<p>Represents a mock object that generates warnings on <a href="../gmock_cook_book.md#uninteresting-vs-unexpected">uninteresting calls</a>. The template parameter <code>T</code> is any mock class, except for another <code>NiceMock</code>, <code><a class="el" href="class_naggy_mock.html">NaggyMock</a></code>, or <code>StrictMock</code>.</p>
<p>Usage of <code><a class="el" href="class_naggy_mock.html">NaggyMock</a>&lt;T&gt;</code> is analogous to usage of <code>T</code>. <code><a class="el" href="class_naggy_mock.html">NaggyMock</a>&lt;T&gt;</code> is a subclass of <code>T</code>, so it can be used wherever an object of type <code>T</code> is accepted. In addition, <code><a class="el" href="class_naggy_mock.html">NaggyMock</a>&lt;T&gt;</code> can be constructed with any arguments that a constructor of <code>T</code> accepts.</p>
<p>For example, the following code generates warnings on the mock <code>my_mock</code> of type <code>MockClass</code> if a method other than <code>DoSomething()</code> is called:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::<a class="code hl_class" href="classtesting_1_1_naggy_mock.html">testing::NaggyMock</a>;</div>
<div class="line">...</div>
<div class="line">NaggyMock&lt;MockClass&gt; my_mock(<span class="stringliteral">&quot;some&quot;</span>, <span class="stringliteral">&quot;args&quot;</span>);</div>
<div class="line">EXPECT_CALL(my_mock, DoSomething());</div>
<div class="line">... code that uses my_mock ...</div>
<div class="ttc" id="aclasstesting_1_1_naggy_mock_html"><div class="ttname"><a href="classtesting_1_1_naggy_mock.html">testing::NaggyMock</a></div><div class="ttdef"><b>Definition</b> gmock-nice-strict.h:192</div></div>
</div><!-- fragment --><p><a class="el" href="class_mock.html">Mock</a> objects of type <code>T</code> by default behave the same way as <code><a class="el" href="class_naggy_mock.html">NaggyMock</a>&lt;T&gt;</code>.</p>
<h2><a class="anchor" id="StrictMock"></a>
StrictMock</h2>
<p><code><a class="el" href="classtesting_1_1_strict_mock.html">testing::StrictMock</a>&lt;T&gt;</code></p>
<p>Represents a mock object that generates test failures on <a href="../gmock_cook_book.md#uninteresting-vs-unexpected">uninteresting calls</a>. The template parameter <code>T</code> is any mock class, except for another <code>NiceMock</code>, <code><a class="el" href="class_naggy_mock.html">NaggyMock</a></code>, or <code>StrictMock</code>.</p>
<p>Usage of <code>StrictMock&lt;T&gt;</code> is analogous to usage of <code>T</code>. <code>StrictMock&lt;T&gt;</code> is a subclass of <code>T</code>, so it can be used wherever an object of type <code>T</code> is accepted. In addition, <code>StrictMock&lt;T&gt;</code> can be constructed with any arguments that a constructor of <code>T</code> accepts.</p>
<p>For example, the following code generates a test failure on the mock <code>my_mock</code> of type <code>MockClass</code> if a method other than <code>DoSomething()</code> is called:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::<a class="code hl_class" href="classtesting_1_1_strict_mock.html">testing::StrictMock</a>;</div>
<div class="line">...</div>
<div class="line">StrictMock&lt;MockClass&gt; my_mock(<span class="stringliteral">&quot;some&quot;</span>, <span class="stringliteral">&quot;args&quot;</span>);</div>
<div class="line">EXPECT_CALL(my_mock, DoSomething());</div>
<div class="line">... code that uses my_mock ...</div>
<div class="ttc" id="aclasstesting_1_1_strict_mock_html"><div class="ttname"><a href="classtesting_1_1_strict_mock.html">testing::StrictMock</a></div><div class="ttdef"><b>Definition</b> gmock-nice-strict.h:234</div></div>
</div><!-- fragment --><p><code>StrictMock&lt;T&gt;</code> only works for mock methods defined using the <code>MOCK_METHOD</code> macro directly in the definition of class <code>T</code>. If a mock method is defined in a base class of <code>T</code>, a failure might not be generated.</p>
<p><code>StrictMock&lt;T&gt;</code> might not work correctly if the destructor of <code>T</code> is not virtual.</p>
<h2><a class="anchor" id="Sequence"></a>
Sequence</h2>
<p><code>::testing::Sequence</code></p>
<p>Represents a chronological sequence of expectations. See the `InSequence` clause of <code>EXPECT_CALL</code> for usage.</p>
<h2><a class="anchor" id="InSequence"></a>
InSequence</h2>
<p><code>::testing::InSequence</code></p>
<p>An object of this type causes all expectations encountered in its scope to be put in an anonymous sequence.</p>
<p>This allows more convenient expression of multiple expectations in a single sequence:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::InSequence;</div>
<div class="line">{</div>
<div class="line">  InSequence seq;</div>
<div class="line"> </div>
<div class="line">  <span class="comment">// The following are expected to occur in the order declared.</span></div>
<div class="line">  EXPECT_CALL(...);</div>
<div class="line">  EXPECT_CALL(...);</div>
<div class="line">  ...</div>
<div class="line">  EXPECT_CALL(...);</div>
<div class="line">}</div>
</div><!-- fragment --><p>The name of the <code>InSequence</code> object does not matter.</p>
<h2><a class="anchor" id="Expectation"></a>
Expectation</h2>
<p><code>::testing::Expectation</code></p>
<p>Represents a mock function call expectation as created by <a class="el" href="#EXPECT_CALL">`EXPECT_CALL`</a>:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::Expectation;</div>
<div class="line">Expectation my_expectation = EXPECT_CALL(...);</div>
</div><!-- fragment --><p>Useful for specifying sequences of expectations; see the `After` clause of <code>EXPECT_CALL</code>.</p>
<h2><a class="anchor" id="ExpectationSet"></a>
ExpectationSet</h2>
<p><code>::testing::ExpectationSet</code></p>
<p>Represents a set of mock function call expectations.</p>
<p>Use the <code>+=</code> operator to add <a class="el" href="#Expectation">`Expectation`</a> objects to the set:</p>
<div class="fragment"><div class="line"><span class="keyword">using </span>::testing::ExpectationSet;</div>
<div class="line">ExpectationSet my_expectations;</div>
<div class="line">my_expectations += EXPECT_CALL(...);</div>
</div><!-- fragment --><p>Useful for specifying sequences of expectations; see the `After` clause of <code>EXPECT_CALL</code>. </p>
</div></div><!-- contents -->
</div><!-- PageDoc -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.13.2 </li>
  </ul>
</div>
</body>
</html>
